home *** CD-ROM | disk | FTP | other *** search
/ Workbench Add-On / Workbench Add-On - Volume 1.iso / BBS-Archive / Dev / ACE_Prgs.lha / speech / sprecog.lha / voicelibrary.doc < prev   
Text File  |  1995-01-29  |  13KB  |  372 lines
  1. *****************************************************************
  2.  
  3.    Voice Recognition for the Amiga
  4.  
  5.    Voice.library (Ver 6.0) by Richard Horne - August 1992
  6.  
  7. *****************************************************************
  8.  
  9. FUNCTION OFFSET DEFINITIONS
  10.  
  11.    _LVOLearn           EQU   -30
  12.    _LVORecognize       EQU   -36
  13.    _LVOAddVoiceTask    EQU   -42
  14.    _LVORemVoiceTask    EQU   -48
  15.    _LVOGainUp          EQU   -54
  16.    _LVOGainDown        EQU   -60
  17.    _LVORecDataAddress  EQU   -66
  18.    _LVORecMapAddress   EQU   -72
  19.    _LVOWordScore       EQU   -78
  20.    _LVOPickSampler     EQU   -84
  21.    _LVOSetVoicePri     EQU   -90
  22.  
  23. ************************* FUNCTION DEFINITIONS ******************
  24.  
  25. >>>>> All variables are long words unless otherwise noted. <<<<<<
  26.  
  27. NOTE:  Voice.library is opened with a call to the exec OpenLibrary
  28. function.  OpenLibrary can fail for one of three reasons:
  29.  
  30. 1.  The voice.library file is not available in the libs: directory or
  31.     cannot be found.
  32.  
  33. 2.  The parallel port is busy.
  34.  
  35. 3.  Voice.library is currently opened and being used by another
  36.     application program.
  37.  
  38. *****************************************************************
  39.  
  40. NAME:      
  41. Learn -- Learn a spoken phrase.
  42.  
  43. OFFSET:      
  44. -30
  45.  
  46. SYNOPSIS:
  47. MapAddress = Learn (MapBuffer, Text, Screen, SequenceNum, X, Y)
  48. d0                  a0         a1    a2      d0           d1 d2
  49.  
  50. FUNCTION:
  51. The "Learn" function stores a frequency map of a spoken word or
  52. phrase.  Each frequency map is made up of 72 long words of data
  53. plus a 16 byte header for the associated ASCII text (304 bytes
  54. total).  "Learn" requires the user to reserve a MapBuffer in
  55. memory equal to the size of vocabulary desired (number of words)
  56. times 304 bytes.  MapBuffer address is passed to "Learn" in a0. 
  57. Address of a null terminated text string representing the word or
  58. phrase to be learned is passed to "Learn" in a1.
  59.  
  60. The "Learn" function will open it's own window on the screen
  61. specified in a2 (use NULL for WBENCHSCREEN), at a position X, Y
  62. specified in d1 and d2.  The user will then be prompted to speak
  63. the specified word or phrase to obtain three good digital
  64. samples.  Internally, these three samples are analyzed for
  65. frequency content and transformed into a frequency map (304
  66. bytes) which is stored in the MapBuffer according to the Sequence
  67. Number specified in d0.  "Learn" returns the memory address
  68. within MapBuffer at which this particular frequency map is
  69. stored.  If "Learn" is intentionally cancelled using the close
  70. gadget of the Learn Window, then a zero will be returned.
  71.  
  72. "Learn" is called separately for each word or phrase in the
  73. vocabulary.  After every word has been learned, MapBuffer will be
  74. filled with a sequence of frequency maps (each 304 bytes).  Then
  75. the "Recognize" or "AddVoiceTask" functions can be called which
  76. will listen to the audio digitizer, compute a frequency map
  77. of incoming words compare them to the words in MapBuffer, and
  78. indicate by Sequence Number which word or phrase is the best
  79. match.  The maximum number of words or phrases in the vocabulary
  80. is 64.
  81.  
  82. Note that you must select an audio sampler (PerfectSound3,
  83. SoundMaster, or Generic) using the "PickSampler" function before
  84. using the "Learn" function.
  85.  
  86. *****************************************************************
  87.  
  88. NAME:
  89. Recognize -- Recognize a spoken word or phrase.
  90.  
  91. OFFSET:
  92. -36
  93.  
  94. SYNOPSIS:
  95. SequenceNum = Recognize (MapBuffer, SizeVocabulary, Resolution)
  96. d0                       a0         d0              d1 
  97.  
  98. FUNCTION:
  99. "Recognize" assumes that the user has learned a sequence of words
  100. or phrases using the "Learn" function.  MapBuffer contains a
  101. sequence of frequency maps produced by "Learn" corresponding to
  102. each word or phrase in the vocabulary.  Mapbuffer address is
  103. passed to "Recognize" in a0.  Number of words or phrases in the
  104. vocabulary are passed to "Recognize" in d0.
  105.  
  106. "Recognize" listens for an incoming word, computes it's frequency
  107. map, and compares this map to the sequence of maps contained in
  108. MapBuffer.  The Sequence Number of the word or phrase in
  109. MapBuffer which is most similar to that of the incoming word is
  110. returned in d0.  Note that the number "0" represents the first
  111. word, "1" the second, and so on.
  112.  
  113. "Recognize" will operate at either high resolution (d1 = 0) or
  114. low resolution (d1 = 1).  High resolution computes a frequency
  115. analysis of the incoming word or phrase at twice the number of
  116. points in time as low resolution.  High resolution is somewhat
  117. better at word recognition, but takes almost twice the processing
  118. time.
  119.  
  120. "Recognize" will return the following error codes if it cannot
  121. find a match.
  122.  
  123. d0 = -1 if there is no match between the incoming frequency map  
  124.    and any of the maps in MapBuffer.
  125.  
  126. d0 = -2 if the incoming word causes unacceptable digital
  127.    clipping.  Volume should be reduced by moving your
  128.    microphone or by using the "GainDown" function.
  129.     
  130. d0 = -3 if incoming word is too low in volume.  Volume should be
  131.    increased by moving your microphone or by using the "GainUp"
  132.    function.
  133.  
  134. d0 = -4 if the incoming sample is confused by extraneous noise.
  135.  
  136. *****************************************************************
  137.  
  138. NAME:      
  139. AddVoiceTask -- Initiate a separate task to recognize a spoken 
  140.                 word or phrase.
  141.  
  142. OFFSET:      
  143. -42
  144.  
  145. SYNOPSIS:
  146. AddVoiceTask (MapBuffer, MsgPort, SizeVocabulary, Resolution)
  147.               a0         a1       d0              d1
  148.  
  149. FUNCTION:
  150. "AddVoiceTask" is similar in function to "Recognize" except that
  151. here, a separate task is started under the Amiga multitasking
  152. operating system which listens for incoming words or phrases and
  153. returns messages to the user's Message Port indicating the
  154. Sequence Number of the frequency map in Mapbuffer which best
  155. matches the frequency map of the incoming word.  MapBuffer
  156. address and Message Port address are passed to "AddVoiceTask"
  157. in a0 and a1.  Number of words or phrases in the vocabulary are
  158. passed to "AddVoiceTask" in d0.
  159.  
  160. "AddVoiceTask" will operate at either high resolution (d1 = 0) or
  161. low resolution (d1 = 1).  High resolution computes a frequency
  162. analysis of the incoming word or phrase at twice the number of
  163. points in time as low resolution.  High resolution is somewhat
  164. better at word recognition, but takes almost twice the processing
  165. time.
  166.  
  167. The messages sent to MessagePort are designed to mimic shortened
  168. IDCMP messages with a im_Class = $0.  Thus you can receive and
  169. process these messages at either an Intuition window IDCMP
  170. message port or at a custom message port of your own.
  171. Messages sent by this task are as follows.
  172.  
  173. im_Code = Sequence number of frequency map in MapBuffer that
  174.           best matches the frequency map of the incoming
  175.           word or phrase.
  176.  
  177. im_Code = -1 if there is no match between the incoming
  178.           frequency map and any of the maps in MapBuffer.
  179.  
  180. im_Code = -2 if the incoming word causes unacceptable
  181.           digital clipping.  Volume should be reduced by
  182.           moving your microphone or by using the "GainDown"
  183.           function.
  184.  
  185. im_Code = -3 if incoming word is too low in volume.  Volume
  186.           should be increased by moving your microphone or
  187.           by using the "GainUp" function.
  188.  
  189. im_Code = -4 if the incoming sample is confused by
  190.           extraneous noise.
  191.  
  192. Upon calling "AddVoiceTask", the PerfectSound digitizer becomes
  193. immediately active, listening for an incoming word.  After
  194. receipt of a word or phrase, a message as described above is sent
  195. to Message Port.  The VoiceTask then goes into a WAIT mode and
  196. remains inactive until it receives a reply to the message it has
  197. sent to Message Port.  Upon receipt of a reply, VoiceTask again
  198. becomes goes active and listens for an incoming word.  The priority
  199. of this task will be 127 for fastest possible voice recognition.
  200. You may change this priority to a lower value with the "SetVoicePri"
  201. task.
  202.  
  203. *****************************************************************
  204.  
  205. NAME:      
  206. RemVoiceTask -- Remove task initiated by AddVoiceTask
  207.  
  208. OFFSET:      
  209. -48
  210.  
  211. SYNOPSIS:
  212. RemVoiceTask ()
  213.    
  214. FUNCTION:
  215. Deallocates memory and removes VoiceTask from the Amiga system.
  216. Note that the Message Port specified for the "AddVoiceTask" function
  217. must still exist at the time you call "RemVoiceTask".
  218.  
  219. *****************************************************************
  220.  
  221. NAME:
  222. GainUp -- Increase gain of PerfectSound 3 audio digitizer.
  223.  
  224. OFFSET:
  225. -54
  226.  
  227. SYNOPSIS:
  228. GainUp()
  229.  
  230. FUNCTION:
  231. Increases gain of the PerfectSound audio digitizer by one step. 
  232. Note that when gain reaches maximum, "GainUp" will wrap around
  233. and return gain to it's lowest value.  Do not call this function
  234. if you are using the SoundMaster audio digitizer.
  235.  
  236. *****************************************************************
  237.  
  238. NAME:
  239. GainDown -- Decease gain of PerfectSound 3 audio digitizer.
  240.  
  241. OFFSET:
  242. -60
  243.  
  244. SYNOPSIS:
  245. GainDown()
  246.  
  247. FUNCTION:
  248. Decreases gain of the PerfectSound audio digitizer by one step. 
  249. Note that when gain reaches minimum, "GainDown" will wrap around
  250. and return gain to it's highest value.  Do not call this function
  251. if you are using the SoundMaster audio digitizer
  252.  
  253. *****************************************************************
  254.  
  255. NAME:
  256. RecDataAddress -- Return memory address of digital sample of
  257.                   incoming word or phrase.
  258.  
  259. OFFSET:
  260. -66
  261.  
  262. SYNOPSIS:
  263. Address = RecDataAddress()
  264. d0
  265.  
  266.  
  267. FUNCTION:
  268. When an incoming word or phrase is digitized, 3/4 second of
  269. digital data is stored in an internal buffer.  This is 8 bit
  270. digitized data is sampled at a rate of 6400 Hz.  Thus the buffer
  271. for storing this data is 4800 bytes in size.  This function
  272. returns the address of this buffer for possible additional
  273. experimental uses.
  274.  
  275. *****************************************************************
  276.  
  277. NAME:
  278. RecMapAddress -- Return memory address of frequency map of
  279.                  incoming word or phrase.
  280.  
  281. OFFSET:
  282. -72
  283.  
  284. SYNOPSIS:
  285. Address = RecMapAddress()
  286. d0
  287.  
  288. FUNCTION:
  289. A frequency map of each incoming word or phrase is computed for
  290. comparison with maps learned and stored in MapBuffer.  Each map
  291. consists of a frequency analysis of 3/4 second of audio data at
  292. 72 points in time.  For each of these 72 time points, the data is
  293. examined for frequency content at 32 points between 0 Hz and 3200
  294. Hz.  A frequency map is made up of 72, 32 bit words corresponding
  295. to the 72 time points analyzed.  For each of these 32 bit words,
  296. bit 0 is set if the signal contains frequency components from 
  297. 0-100 Hz.  Bit 1 is set if the signal contains frequency
  298. components from 100-200 Hz.  Bit 2 is set if the signal contains
  299. frequency components from 200-300 Hz etc.  This function returns
  300. the address of this frequency map for possible additional
  301. experimental uses.  Note that this internal frequency map does
  302. not have the 16 byte ASCII header as do the frequency maps
  303. stored in MapBuffer.
  304.  
  305. *****************************************************************
  306.  
  307. NAME:
  308. WordScore -- Return recognition score of a recognized word.
  309.  
  310. OFFSET:
  311. -78
  312.  
  313. SYNOPSIS:
  314. Value = WordScore()
  315. d0
  316.  
  317. FUNCTION:
  318. The "Recognize" function computes a numerical score representing the
  319. "goodness" of a match between the frequency map of an incoming word
  320. and each frequency map stored in MapBuffer.  The recognized word
  321. is determined by highest score.  This function returns the score value
  322. for the recognized word.  Internally, a score of #2000 must be achieved
  323. in order for a match to be declared.  If you wish to have a higher match
  324. score threshold to reduce false matches, you may call "WordScore" after
  325. each word is recognized and set your own higher score threshold before
  326. accepting a match.  Increasing the match score threshold will reduce
  327. false matches, but will also decrease recognition performance.
  328.  
  329.  
  330. *****************************************************************
  331.  
  332. NAME:      
  333. PickSampler -- Specify which model audio sampler to use (either
  334.                PerfectSound3, SoundMaster, or Generic).
  335.  
  336. OFFSET:      
  337. -84
  338.  
  339. SYNOPSIS:
  340. PickSampler (SamplerID)
  341.                 d0
  342.  
  343. FUNCTION:
  344. Select the audio sampler to be used with this function.  SamplerID = 0
  345. for PerfectSound3.  SamplerID = 1 for SoundMaster.  SamplerID = 2 for
  346. Generic Sampler.
  347.  
  348. *****************************************************************
  349.  
  350. NAME:
  351. SetVoicePri -- Set the multitasking priority of a voice recognition
  352.                task that has been started by the "AddVoiceTask"
  353.                function.
  354.  
  355. OFFSET:
  356. -90
  357.  
  358. SYNOPSIS:
  359. Old Priority = SetVoicePri (New Priority)
  360. d0                          d0
  361.  
  362. FUNCTION:
  363. When "AddVoiceTask" is called, a voice recgnition task of priority 127
  364. is started for the fastest possible voice recognition.  You may modify
  365. this priority by setting New Priority to any value between -128 and 127
  366. and calling "SetVoicePri" which changes task priority to the new value
  367. and returns the value of the old task priority.  "AddVoiceTask" must
  368. be called before "SetVoicePri."
  369.  
  370. *****************************************************************
  371.  
  372.